How to Build a Collaboration Service

Introduction

What is a Collaboration Service?

A Collaboration Service is a service that can be launched to collaborate with a single person or a group of people. Examples for such services are Send Email, Share Application or Dial Phone.

In the Knowledge Management & Collaboration applications Collaboration Services are available in the Collaboration Launch Pad or Team Member List and wherever a user or a group is displayed using the so-called PeopleRenderer control. A portal user can access and launch the services via the respective context menus.

It is possible to write your own Collaboration Service and make it available via configuration.

Technical View

When an application like the Collaboration Launch Pad or a PeopleRenderer control launches a Collaboration Service they create a container and put the respective users or groups into it. On launch of the Collaboration Service the service retrieves the users or groups from the container and uses them in its application logic.

From a technical point of view a Collaboration Service is a portal component which makes use of the so-called ContextContainer. The ContextContainer carries the list of people involved in Collaboration Service's action.

The Example

In the following chapter the implementation of a Collaboration Service sample is shown.

Source Code

The portal component implementing the Collaboration Service is a usually a HTMLB DynPage application. Therefore we have to implement two classes: the PageProcessorComponent and the DynPage.

PageProcessorComponent of Sample Collaboration Service

As in most cases the PageProcessorComponent implementation only returns the DynPage:

package sample.collaborationservice;

import com.sapportals.htmlb.page.DynPage;
import com.sapportals.portal.htmlb.page.PageProcessorComponent;

public class SampleCollaborationService extends PageProcessorComponent {
    public DynPage getPage() {
        return new SampleCollaborationServicePage();
    }
}

DynPage of Sample Collaboration Service

Below you can find the source of the DynPage. All important lines will be explained in more details later on.

package sample.collaborationservice;

import java.util.ArrayList;

import com.sap.netweaver.kmc.people.shared.ctx.ContextContainer;
import com.sapportals.htmlb.page.DynPage;
import com.sapportals.htmlb.page.PageException;
import com.sapportals.htmlb.rendering.IPageContext;
import com.sapportals.portal.prt.component.IPortalComponentRequest;

public class SampleCollaborationServicePage extends DynPage {

public void doProcessBeforeOutput() throws PageException {
         IPageContext pc = getPageContext();
         IPortalComponentRequest request = (IPortalComponentRequest)pc.getRequest();

         // Use the PortalComponentRequest to create the ContextContainer.
         ContextContainer container = new ContextContainer(request);
         try {
                 // Retrieve flat list of UniqueIds of Principals
                 ArrayList peopleIdList = container.getResolvedPeopleList();

                 // @TODO put your application logic here

         } catch (Exception e) {
                 throw new PageException(e);
         }
}

public void doInitialization()    throws PageException {}
public void doProcessAfterInput() throws PageException {}
}

In order to work with the principals (users, groups, roles) provided by either the Collaboration Launch Pad or the PeopleRenderer, you need to instantiate a ContextContainer. You can then call the methods on the ContextContainer to get an ArrayList which contains all principals. See Javadoc for details.

Configuration of the Collaboration Services

In this chapter you can find the steps that are necessary to create the Configurables for your Collaboration Service.

See also the Collaboration Services documentation [ColService Doc] for details on how to reference the Configurables in the configuration.

Configuration Path

The Configurables must be deployed to the configuration path "Collaboration - Properties - LinkCommand ".

Configurables of Type LinkCommand

For each Collaboration Service you need to create two Configurables of type LinkCommand.

The Configurables only differ in the underlying Java implementation that is used:

Usage	Java Implementation Class
PeopleRenderer control, User Details dialog	com.sap.netweaver.coll.coreui.api.uicommands.UILaunchCommand
Collaboration Launch Pad, Team Member List	com.sap.ip.collaboration.coreui.api.people.flexibleui.CLPUICommand

Note: even if your Collaboration Service can only deal with a single user, you should create two Configurables because otherwise the Collaboration service cannot be launched for single users that were selected in the Collaboration Launch Pad.

LinkCommand Details

In the table below you can see all attributes of a LinkCommand Configurable:

Attribute	Description of Value or Sample Value	Fixed or Custom
javaClass	com.sap.netweaver.coll.coreui.api.uicommands. UILaunchCommand or com.sap.ip.collaboration.coreui.api.people. flexibleui.CLPUICommand
reference	Reference to the full-qualified name of the portal application as specified in the portalapp.xml file prefixed with 'portal:', e.g. portal:sample.portal.app.CollaborationService
resourceBundle	Name of the resource bundle file as registered with the CRT (see also 2.3), e.g. sample.collaborationservice.MyBundle
labelKey	Key of label in resource bundle file
tooltipKey	Key of label in resource bundle file
positionType	center or custom
height, width	Integer value specifying the window dimension
top, left	Integer value specifying the window position, only relevant if positionType equals custom
valueFactoryKey	LinkCommandValueFactory	Fixed
launchType	modalPopup	Fixed
ridPathName	Uri	Fixed
windowName	Not used, empty value	Fixed
applicationParameters	Not used, empty value	Fixed
urlParameters	Not used, empty value	Fixed
portalRoles	See documentation of Collaboration Services

The last column specifies whether the attribute should be changed or not.

Example of a LinkCommand Configurable

Find below a full example for a LinkCommand Configurable:

<?xml version="1.0"  encoding="UTF-8" ?>
<Configurable configclass="LinkCommand">
   <property name="name" value="MyCollaborationService"/>
   <property name="javaClass"
              value="com.sap.netweaver.coll.coreui.api.uicommands.UILaunchCommand"/>
   <property name="reference"
              value="portal:sample.portal.app.CollaborationService"/>
   <property name="resourceBundle"  value="sample.collaborationservice.MyBundle"/>
   <property name="labelKey"        value="XLAB_COLL_SERVICE"/>
   <property name="tooltipKey"      value="XTOL_COLL_SERVICE"/>
   <property name="positionType"    value="custom"/>
   <property name="height"          value="340"/>
   <property name="width"           value="200"/>
   <property name="top"             value="20"/>
   <property name="left"            value="20"/>
   <property name="valueFactoryKey" value="LinkCommandValueFactory"/>
   <property name="launchType"      value="modalPopup"/>
   <property name="ridPathName"     value="Uri"/>
   <property name="windowName" />
   <property name="applicationParameters" />
   <property name="urlParameters" />
   <property name="portalRoles" />
</Configurable>

The attribute values in bold are the ones which will differ in your configurable.

Note: You must adhere to the naming conventions for Configurable files names. See [Config Fwk] for details.

Internationalization

The context menu entry of your Collaboration Service can be internationalised by using standard Java technology.

Therefore you need to add two properties for the label and the tool tip of the Collaboration Service in a resource bundle.

These properties are referenced in the Configurable as described in the previous chapter.

Note: The resource bundle files need to be registered with the CRT. For a detailed description see [RF CRT Config].

References

[ColService Doc]: See chapter "Collaboration Services" and here "Configuration" in the EP standard documentation.

[RF CRT Config]: See chapter "Config Handling" in the Repository Framework chapter "How to use RF's Repository Services".

[Config Fwk]: See chapter "Config Framework" in KMC_Documentation_Eclipse